Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Advertise deprecated endpoints via Deprecation headers ( draft-ietf-httpapi-deprecation-header-03 ) #30308

Open
ThisIsMissEm opened this issue May 15, 2024 · 3 comments
Labels
suggestion Feature suggestion

Comments

@ThisIsMissEm
Copy link
Contributor

ThisIsMissEm commented May 15, 2024

Pitch

Currently notices of deprecated endpoints are exclusively listed in that endpoints' documentation Version History. This means that people may not notice that they are using deprecated endpoints, and API Clients can't automatically warn when a deprecated API is used.

I'd like to propose that we adopt draft-ietf-httpapi-deprecation-header-03, and advertise as follows:

Deprecation: @1688169599
Link: <https://docs.joinmastodon.org/api/deprecations#<id>; rel="deprecation"; type="text/html"

Where 1688169599 is when the endpoint was or will be deprecated at, in seconds; and <id> is a unique identified for that deprecation on the deprecation pages.

We may also have use in the Sunset HTTP Header, however, this would require fairly exact release dates, which we don't currently have, or we use the sunset rel in a Link header, to indicate upcoming removal of an API. (but I'm not sure if we've ever completely removed an API, a breaking change.

There is a ticket on the documentation repository which is complementary to this.

Motivation

This will help developers be better able to discover when they're using outdated API endpoints, and help them upgrade, ensuring a healthier API community usage.

@LucasGGamerM
Copy link

I am in favor of this

@VyrCossont
Copy link
Contributor

VyrCossont commented May 15, 2024

Makes sense for client library developers and bot operators, who would be in a position to see error messages if their client library was aware of these headers. I assume this isn't meant to be surfaced to end users.

@ThisIsMissEm
Copy link
Contributor Author

I assume this isn't meant to be surfaced to end users.

@VyrCossont correct! Though, if you're a developer using a client library, then the client library may choose to expose this information to you via logging.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
suggestion Feature suggestion
Projects
None yet
Development

No branches or pull requests

3 participants